---
title: Docker를 사용하여 Astro 사이트 빌드
description: Docker를 사용하여 Astro 사이트를 빌드하는 방법을 알아보세요.
type: recipe
i18nReady: true
---

[Docker](https://docker.com)는 컨테이너를 사용하여 애플리케이션을 빌드, 배포, 실행하는 도구입니다.

Docker 이미지와 컨테이너는 AWS, Azure, [Google Cloud](/ko/guides/deploy/google-cloud/#cloud-run-ssr-및-정적) 등 다양한 플랫폼에 배포할 수 있습니다. 이 레시피에서는 사이트를 특정 플랫폼에 배포하는 방법을 다루지 않지만 프로젝트에 Docker를 설정하는 방법을 보여줍니다.

## 전제조건

- 로컬 컴퓨터에 Docker가 설치되어 있어야 합니다. [여기에서 운영 체제에 대한 설치 지침](https://docs.docker.com/get-docker/)을 찾을 수 있습니다.
- 프로젝트의 Dockerfile이 있어야 합니다. [여기에서 Dockerfile에 대해 자세히 알아보고](https://docs.docker.com/engine/reference/builder/) 다음 섹션의 Dockerfile을 시작점으로 사용할 수 있습니다.

## Dockerfile 생성

프로젝트의 루트 디렉터리에 `Dockerfile`이라는 파일을 만듭니다. 이 파일에는 사이트를 빌드하기 위한 지침이 포함되어 있으며, 이는 필요에 따라 달라집니다. 이 가이드는 가능한 모든 옵션을 표시할 수는 없지만 SSR 및 정적 모드에 대한 시작점을 제공합니다.

npm이 아닌 다른 패키지 관리자를 사용하는 경우 이에 따라 명령을 조정해야 합니다.

### SSR

이 Dockerfile은 사이트를 빌드하고 `4321` 포트에서 Node.js를 사용하여 제공하므로 Astro 프로젝트에 [Node 어댑터](/ko/guides/integrations-guide/node/)가 설치되어 있어야 합니다.

```docker title="Dockerfile"
FROM node:lts AS runtime
WORKDIR /app

COPY . .

RUN npm install
RUN npm run build

ENV HOST=0.0.0.0
ENV PORT=4321
EXPOSE 4321
CMD node ./dist/server/entry.mjs
```

:::tip[기억하세요]
이는 Dockerfile의 예시일 뿐입니다. 필요에 따라 사용자 정의할 수 있습니다. 예를 들어 `node:lts-alpine`과 같은 다른 이미지를 사용할 수 있습니다.

```docker title="Dockerfile" del={1} add={2}
FROM node:lts as runtime
FROM node:lts-alpine as runtime
```
:::

### .dockerignore 추가

프로젝트에 `.dockerignore` 파일을 추가하는 것이 가장 좋습니다. 이 파일은 Docker `COPY` 또는 `ADD` 명령에서 무시해야 하는 파일이나 폴더를 설명하며 `.gitignore` 작동 방식과 매우 유사합니다. 이렇게 하면 빌드 프로세스 속도가 빨라지고 최종 이미지의 크기가 줄어듭니다.

```docker title=".dockerignore"
.DS_Store
node_modules
dist
```

이 파일은 `Dockerfile` 자체와 동일한 디렉터리에 있어야 합니다. [추가 정보는 `.dockerignore` 문서를 읽어보세요.](https://docs.docker.com/engine/reference/builder/#dockerignore-file)

### 정적

#### Apache (httpd)

다음 Dockerfile은 기본 구성으로 포트 `80`에서 Apache httpd를 사용하여 사이트를 빌드하고 제공합니다.

```docker title="Dockerfile"
FROM node:lts AS build
WORKDIR /app
COPY . .
RUN npm i
RUN npm run build

FROM httpd:2.4 AS runtime
COPY --from=build /app/dist /usr/local/apache2/htdocs/
EXPOSE 80
```

:::caution[권장사항]
특별한 구성이 필요하지 않은 간단한 웹사이트에 이 접근 방식을 사용하세요. 보다 복잡한 웹사이트의 경우 Apache 또는 NGINX에서 사용자 정의 구성을 사용하는 것이 좋습니다.
:::

#### NGINX

```docker title="Dockerfile"
FROM node:lts AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine AS runtime
COPY ./nginx/nginx.conf /etc/nginx/nginx.conf
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 8080
```

위 Dockerfile을 빌드하려면 NGINX용 구성 파일도 만들어야 합니다. 프로젝트의 루트 디렉터리에 `nginx`라는 폴더를 만들고 그 안에 `nginx.conf`라는 파일을 만듭니다.

```nginx title="nginx.conf"
worker_processes  1;

events {
  worker_connections  1024;
}

http {
  server {
    listen 8080;
    server_name   _;

    root   /usr/share/nginx/html;
    index  index.html index.htm;
    include /etc/nginx/mime.types;

    gzip on;
    gzip_min_length 1000;
    gzip_proxied expired no-cache no-store private auth;
    gzip_types text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript;

    error_page 404 /404.html;
    location = /404.html {
            root /usr/share/nginx/html;
            internal;
    }

    location / {
            try_files $uri $uri/index.html =404;
    }
  }
}
```

### Multi-stage 빌드 (SSR 사용)

다음은 Docker의 [multi-stage 빌드](https://docs.docker.com/build/building/multi-stage/) 덕분에 소스 코드만 변경될 때 npm 종속성을 다시 설치하지 않고 사이트의 빌드 프로세스를 최적화하는 고급 Dockerfile의 예시입니다. 종속성 크기에 따라 빌드 시간을 몇 분 단위로 줄일 수 있습니다.

```docker title="Dockerfile"
FROM node:lts AS base
WORKDIR /app

# 여기에서는 package.json 및 package-lock.json만 복사하여 다음 `-deps` 단계가 소스 코드와 독립적인지 확인합니다.
# 따라서 소스 코드만 변경되면 `-deps` 단계를 건너뜁니다.
COPY package.json package-lock.json ./

FROM base AS prod-deps
RUN npm install --production

FROM base AS build-deps
RUN npm install --production=false

FROM build-deps AS build
COPY . .
RUN npm run build

FROM base AS runtime
COPY --from=prod-deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist

ENV HOST=0.0.0.0
ENV PORT=4321
EXPOSE 4321
CMD node ./dist/server/entry.mjs
```

## 레시피

1. 프로젝트의 루트 디렉터리에서 다음 명령을 실행하여 컨테이너를 빌드합니다. `<your-astro-image-name>`에 아무 이름이나 사용하세요.

```bash
docker build -t <your-astro-image-name> .
```

그러면 로컬에서 실행하거나 선택한 플랫폼에 배포할 수 있는 이미지가 출력됩니다.

2. 이미지를 로컬 컨테이너로 실행하려면 다음 명령을 사용합니다.

`<local-port>`를 기기의 오픈 포트로 바꾸세요. `<container-port>`를 Docker 컨테이너에 의해 노출된 포트 (위 예시에서는 `4321`, `80`, `8080`)로 바꿉니다.

```bash
docker run -p <local-port>:<container-port> <your-astro-image-name>
```

`http://localhost:<local-port>`에서 사이트에 액세스할 수 있어야 합니다.

3. 이제 웹 사이트가 성공적으로 빌드되어 컨테이너에 패키징되었으므로 이를 클라우드 공급자에 배포할 수 있습니다. 한 가지 예시는 [Google Cloud](/ko/guides/deploy/google-cloud/#cloud-run-ssr-및-정적) 배포 가이드와 Docker 문서의 [앱 배포](https://docs.docker.com/language/nodejs/deploy/) 페이지를 참조하세요.